package tcln.sors.client.core.mvc;

import java.util.Map;

import tcln.sors.client.core.mvc.modelmapping.ModelDataMapper;
import tcln.sors.client.core.mvc.modelmapping.ModelDataPopulator;

/**
 * Interface for a <b>Controller</b> component in MVC architecture.
 * 
 * @param <M>
 *            Model class.
 * @author Truong Chau Lien Ngoc (lienngoc@gmail.com)
 */
public interface Controller<M extends ModelData<?>> {

    /**
     * Initializes this controller base on given request parameters.
     * <p>
     * <b>Notes</b>:
     * <ul>
     * <li>This method is invoked only once when this controller is constructed by the application controller.
     * <li>This method is invoked by {@link ApplicationController} before this controller is ready for use.
     * <li>Usually, this method is used to build model data which is useful for display.
     * </ul>
     * 
     * @param requestParameters
     */
    void initialize(Map<String, Object> requestParameters);

    /**
     * Fires when this controller is ready to show its view.
     * <p>
     * <b>Notes</b>:
     * <ul>
     * <li>This method is invoked everytime this controller is to be returned for use.
     * <li>Usually, this method is used to update/re-build model data.
     * </ul>
     */
    void onReady();

    /**
     * Sets a view for this 'realizable' object.
     * <p>
     * <b>Note</b>: This method is intended to be called by {@link ApplicationController}, not manually by client code.
     * 
     * @param view
     */
    void setView(View<?> view);

    /**
     * Shows the attached view of this controller in the center of the container view.
     * 
     * @param center
     *            <code>true</code> to force this view to be shown in the center of the owner screen.
     */
    void showView(boolean center);

    /**
     * Shows the attached view of this controller in 'modal' mode.
     * 
     * @param center
     *            <code>true</code> to force this view to be shown in the center of the owner screen.
     */
    void showViewModal(boolean center);

    /**
     * Returns a unique identifier for the type of this controller.
     * 
     * @return
     */
    String getType();

    /**
     * Returns current model data.
     * <p>
     * According to the workflow of MVC, this model should be accessible only after method {@link #initialize(Map)} or
     * {@link #onReady()} finishes.
     * 
     * @return
     */
    M getCurrentModel();

    /**
     * Sets model data mapper for this controller.
     * 
     * @param mapper
     */
    void setModelDataMapper(ModelDataMapper mapper);

    /**
     * Sets model data populator for this controller.
     * 
     * @param populator
     */
    void setModelDataPopulator(ModelDataPopulator populator);
}
